Skip to content

Agent skills: restructure into Agents/skills and develop authoring guidance - #72

Open
tlmquintino wants to merge 4 commits into
mainfrom
agent-skills-restructure
Open

Agent skills: restructure into Agents/skills and develop authoring guidance#72
tlmquintino wants to merge 4 commits into
mainfrom
agent-skills-restructure

Conversation

@tlmquintino

Copy link
Copy Markdown
Member

Purpose

Groundwork for further development of the Codex agent skills.

This PR is being developed incrementally. It starts with the directory
restructure and will go on to expand the skills README into proper authoring
guidance, and to add further reusable skills.

Done so far

1. Agent Skills/Agents/skills/

Introduces a top-level Agents/ area with skills/ beneath it, so future agent
artefacts (subagents, prompts, evaluation material) have an obvious home rather
than accumulating in a skills-only directory.

  • git mv (rename detected — no content change to the skills themselves)
  • inbound links updated: root README.md, Guidelines/Ai-Contributions-To-Software.md,
    Legal/Open-Sourcing-Software.md, ADR/ADR-009-Repository-Audit-Store.md
  • outbound relative links inside the moved files corrected for the extra level
    (../../../ in the skills README; ../../../../../ in both SKILL.mds)
  • link check: 0 broken

Planned in this PR

  • Rewrite Agents/skills/README.md as authoring guidance: how to write skills
    to the Agent Skills specification
    (frontmatter fields and constraints, progressive disclosure, scripts/,
    references/, assets/, size budgets, validation), plus installation
    instructions per harness based on the
    client list.
    The current README predates the specification and still says "there is no
    cross-vendor standard for agent skills yet" — that is now out of date.
  • Additional reusable skills, ported to be project- and language-agnostic.
    Candidates are being evaluated and will be proposed before they are written.

Notes for review

Reviewing commit-by-commit is easiest — the rename is isolated in its own commit.

Introduces a top-level `Agents/` area with `skills/` beneath it, so that
future agent artefacts (subagents, prompts, evaluation material) have an
obvious home alongside skills rather than accumulating in a single
skills-only directory.

- git mv "Agent Skills" -> Agents/skills (rename detected; no content change)
- update all inbound links: root README, Guidelines/Ai-Contributions-To-Software,
  Legal/Open-Sourcing-Software, ADR-009
- fix outbound relative links inside the moved files, which are now one level
  deeper (../ -> ../../ in the skills README; ../../ -> ../../../ in both
  SKILL.md files)

Link check: 0 broken. The remaining bare `](LICENSE)` references are inside
template blocks showing what a target repository's README should contain, not
links within the Codex.
The previous README predated a cross-vendor standard and stated that none
existed. The Agent Skills specification (https://agentskills.io/specification)
now fills that gap, so this rewrites the README around it.

Adds:
- what a skill is, and the progressive-disclosure model agents use
- directory layout (SKILL.md, scripts/, references/, assets/)
- the full frontmatter table with the specification's constraints, including
  the name regex and the rule that name must match the directory
- guidance on writing the body: explicit decision rules, stop conditions, and
  restating the trigger outside the frontmatter
- size budgets per load stage, and the 500-line SKILL.md ceiling
- validation via skills-ref
- ECMWF house rules layered on the specification: report-and-gate,
  model-agnostic, never invent or hide findings, redact secrets, British
  English, project-agnostic
- installation paths per harness, preferring the vendor-neutral
  .agents/skills/ location, plus a table of per-product setup documentation
  from https://agentskills.io/clients
- a checklist for contributing a new skill
Ports five workflows into project- and language-agnostic skills written to
the Agent Skills specification. Each discovers the repository's own build,
test and documentation layout rather than hard-coding paths, tools or
organisation names.

- review-pull-request — works through review feedback until it converges.
  Merges two prior workflows (respond-to-review and the Copilot review loop),
  since the mechanics are identical and only the reviewer differs. Records the
  hard-won bot mechanics: the literal `[bot]` reviewer suffix is the only
  request form that works, and the `requested_reviewers` list cycling back to
  empty is the terminating signal. Notes that `gh pr view` does not show inline
  comments, so the GraphQL reviewThreads query is required. Never merges.
- doc-fact-check — executes runnable doc examples and verifies falsifiable
  claims against source. Keeps the distinction between a documentation bug and
  an environment problem, and refuses to invent imports to make a block run.
  Proposes fixes without applying them.
- onboard-repository — read-only survey producing a structured mental model.
  Trusts code over documents and reports the drift between them.
- robustness-audit — merges error-handling and edge-case auditing, which belong
  together: an unhandled edge case usually surfaces as a bad error. Severity
  ladder led by silent-wrong-answer. Asks before changing ambiguous or public
  behaviour.
- improve-code-coverage — treats coverage as a proxy rather than a goal.
  Categorises each gap (testable / defensive / dead / environment-specific),
  prioritises by risk over line count, and deletes dead code rather than
  suppressing it.

Also splits the README index into governance skills (which gate and never act)
and development skills (which may change code, but still never merge, publish
or release, and ask before changing public behaviour).

All five validate against the specification: name matches directory, name
regex and length, description present and within 1024 characters, no unknown
frontmatter keys, and each SKILL.md under the 500-line ceiling.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Found by running the skill against this very pull request: Copilot replied
with 'unable to review ... reached their quota limit'. That is posted as a
review, so the review count rises while no finding is produced.

An agent following the previous wording would treat the rising count as
findings and loop forever: every retry posts another error review, so the
count keeps rising and the no-new-review stop condition is never reached.

Adds a third polling outcome for a service-error review, with the rule to read
the review body before treating a rising count as findings, a cap of one
retry, and an explicit instruction to report that the pull request has NOT
been reviewed — so an unreviewed pull request is never mistaken for a clean
one.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants